Linux Cubed Series 2: Applications

home *** CD-ROM | disk | FTP | other *** search

/ Linux Cubed Series 2: Applications / Linux Cubed Series 2 - Applications.iso / editors / emacs / xemacs / xemacs-1.006 / xemacs-1 / lib / xemacs-19.13 / info / oo-browser.info-2 < prev next >

Wrap

GNU Info File | 1995-09-01 | 48.5 KB | 1,203 lines

This is Info file ../info/oo-browser.info, produced by Makeinfo-1.63 from the input file oo-browser.texi. File: oo-browser.info, Node: Graphical Browsing, Prev: Completing Names, Up: Usage Graphical OO-Browser Interfaces =============================== The X interface to the OO-Browser is called, "xoobr". It provides a simple but effective means of navigating through OO-Browser hierarchy and element relations. (The NEXTSTEP OO-Browser is very similar to the X version, so use the documentation herein if you need any help with it.) Any number of xoobr sessions may be established at the same time. Each one is used to gain a particular view on an Environment. The textual OO-Browser is used to filter a set of classes for display in an xoobr process. For this reason, xoobr is invoked from within the textual OO-Browser. If running under the X window system, Action Key click on the following filename to view a picture of the X OO-Browser: "im/oobr-x.xwd". {`M-g'} `(br-tree-graph)' displays the current listing buffer's entries in a graphical form. It ignores the show features setting so that you can capture the current listing without the need to alter that setting. {`M-d'} `(br-tree)' selects the current class and displays its descendancy graph in tree-form by starting a new xoobr session. With a prefix argument, {`C-u M-d'}, displays descendancy trees for all classes at the current browser level. They are all grouped under some imaginary joining node so as to maintain the concept of one tree per xoobr view. {`M-f'} `(br-tree-features-toggle)' is used before creating a graphical descendency view to determine whether or not to include the features of each class in the listing as child nodes of the class. It toggles between showing features and not showing them in descendancy views. The setting applies across all OO-Browser languages. The default setting is to not add features to the view. Xoobr views are meant to complement the textual browser interface. Therefore, the two most common actions used in the text browser are performed in a similar manner within an xoobr view. A click on a node with the left mouse button highlights the node and then displays the appropriate class text in the chosen editor, ready for editing. A click of the middle button performs similarly but displays the associated class for viewing only. [The right mouse button is disable in this release of the X OO-Browser because of an inability to debug a problem in limiting its use to tree nodes.] The right mouse button when depressed over a node displays a short menu of commands that may be applied to the node. The only ones of real interest at this point are the collapse and expand entries which let you hide and then restore the display of a node's subtree. This allows you precise control over the amount of detail you receive in various parts of the hierarchy. The Help button in the upper right of the an xoobr session window when selected displays a few pages of help text regarding the program itself. The {`M-k'} `(br-tree-kill)' command will prompt to see if you want to terminate all xoobr sessions started from within the current editor session. If you answer affirmatively, all such processes disappear, as your screen will quickly indicate. The upper left of a session window contains a set of buttons which display menus. The only menu entry you need be concerned with at all is found under the file menu, labelled "Quit". xoobr processes may also be terminated by issuing the kill command mentioned just before. A third menas of killing such processes is by sending the permanent `(br-quit)' command, {`C-u q'}, to the textual browser. You will then be prompted as to whether you want to terminate all xoobr sessions started from within the current editor session. File: oo-browser.info, Node: Options, Next: Customization, Prev: Usage, Up: Top OO-Browser Options ****************** * Menu: * External Viewing:: Using An External Viewer or Editor * Keep Viewed Classes:: * Inhibit Version:: Inhibit Version Screen * Invert Ancestors:: Invert Ancestor Trees * Save All:: Save All Lookup Tables * Use Children:: Build Children Lookup Table * Sort Options:: Controlling Class Listing Order File: oo-browser.info, Node: External Viewing, Next: Keep Viewed Classes, Prev: Options, Up: Options Using an External Viewer or Editor ================================== The OO-Browser allows you to select your desired editor and viewer programs when you use a multi-windowed display. By default, both of these tasks are handled by Emacs so that the browser works on text terminals. If you choose an external editor or viewer, Emacs will still automatically be used whenever you invoke the browser from a text terminal. If you wish to edit classes displayed by the browser in an editor other than Emacs, set the BR-EDITOR-CMD variable to the command with which you wish to edit. Arguments to the command should be placed in the variables named BR-ED[1-9], with one string argument per variable. Unused variables should have the value `nil'. Bear in mind that the command must generate a new window under your window system. For example, the vi editor under UNIX does not create its own window, it runs within the window in which it is created. Under X one would create a new xterm window and then invoke vi. The command line would be *xterm -e vi*, the settings in your personal initialization file would then be: ` (setq br-editor-cmd "xterm" br-ed1 "-e" br-ed2 "vi" br-ed3 nil br-ed4 nil br-ed5 nil br-ed6 nil br-ed7 nil br-ed8 nil br-ed9 nil)' This editor will only be used when the browser is run under a window system external to Emacs, like X. (In such a case, the Emacs variable WINDOW-SYSTEM will be non-nil). If you want to view classes in a read-only fashion outside of Emacs, set the following BR-VIEWER-CMD and BR-VW[1-9] variables in a similar manner as you did for the editor variables above. For example, to use `xmore', an X-compatible version of `more', as your viewer, use the following settings (assuming all the BR-VW variables are already null): `(setq br-viewer-cmd "xmore")' File: oo-browser.info, Node: Keep Viewed Classes, Next: Inhibit Version, Prev: External Viewing, Up: Options Keep Viewed Classes =================== The BR-KEEP-VIEWED-CLASSES flag is turned off by default, indicating that each time a class is viewed immediately after another one, the prior one is deleted. If it is set to any non-nil value, all viewed classes are left around for selection. In typical use, the burden of having to manage all viewed classes is greater than the benefit of leaving them in memory. This is why the flag is off by default. The class buffer menu can be used to delete buffers when you want to trim down the number with which you are dealing. *Note Using the Mouse::, for details on this technique. The value of the BR-KEEP-VIEWED-CLASSES flag may be easily toggled with the `(br-toggle-keep-viewed)' command bound to {`V'}. File: oo-browser.info, Node: Inhibit Version, Next: Invert Ancestors, Prev: Keep Viewed Classes, Up: Options Inhibit Version Screen ====================== After you are familiar with the opening OO-Browser version screen, you may want to disable its display each time the browser is started. This is done by setting BR-INHIBIT-VERSION non-nil, as in the following line that would go in your personal OO-Browser initialization file: `(setq br-inhibit-version t)' This option has no effect on the display of the help screen which follows the version screen. Even with this option set, you may display the version screen at any time from within a browser listing window by using {`C-c #'} `(br-version)'. File: oo-browser.info, Node: Invert Ancestors, Next: Save All, Prev: Inhibit Version, Up: Options Invert Ancestor Trees ===================== *Note Browsing Descendants and Ancestors: Descendants and Ancestors, for more information. This is a global OO-Browser option, it affects all Environments. Ancestor trees are normally shown to emphasize how the trees branch out from their origin. An initialization file line such as: `(setq br-invert-ancestors t)' will cause the display of ancestor trees to be inverted such that the further ancestors appear as roots of the trees and parents (the nearest ancestors) appear as leaves in the trees. This ensures that all listing displays reflect the class inheritance structure with children below parents. File: oo-browser.info, Node: Save All, Next: Use Children, Prev: Invert Ancestors, Up: Options Save All Lookup Tables ====================== This is an Environment-specific option set during Environment specification. *Note Creating Environments::. Half of the browser lookup tables can be built whenever an Environment is loaded. If this option is set, these tables will be stored in the Environment file instead. This will speed Environment loading somewhat, at the cost of doubling the file size per saved Environment. File: oo-browser.info, Node: Use Children, Next: Sort Options, Prev: Save All, Up: Options Build Children Lookup Table =========================== This is an Environment-specific option set during Environment specification. *Note Creating Environments::. This is a highly recommended option that allows for fast descendant lookups. The only time one would turn off this option would be when a file system is extremely short of space. File: oo-browser.info, Node: Sort Options, Prev: Use Children, Up: Options Controlling Class Listing Order =============================== The OO-Browser normally orders classes and elements in listing windows according to the ASCII character set. This sort order is controlled by the BR-SORT-OPTIONS variable which specifies the command line options sent to the system `sort' command. (Under any Emacs 19 variant, this variable is not used by the `br-order' command, bound to {`o'}.) The value of this variable should be a single string of options such as `-fu' (the default) or `nil' for no options. The `-f' option folds upper and lower case to the same character for sort comparisons. The `-u' option leaves only unique elements in the listing by eliminating any duplicate entries. File: oo-browser.info, Node: Customization, Next: Standalone, Prev: Options, Up: Top Personal Customization ********************** The following hook variables are provided so that one may customize what happens each time the OO-Browser is invoked. Set them as you would any other Emacs Lisp hook variables in a personal OO-Browser initialization file, `~/.br-init.el'. They all default to null operations. If you want a set of actions to occur each time after the OO-Browser is invoked, attach them to BR-MODE-HOOK. For language-specific actions, a language-specific hook such as BR-EIF-MODE-HOOK, or BR-C++-MODE-HOOK is run after BR-MODE-HOOK. If you want a set of actions to occur after each time that a new browser listing buffer is created, set BR-CLASS-LIST-HOOK. File: oo-browser.info, Node: Standalone, Next: Languages, Prev: Customization, Up: Top Using Standalone OO-Browser Features ************************************ A number of browser features may be used independently of the browser user interface, assuming that a site-wide or personal OO-Browser initialization file has been loaded into your current Emacs session. First, an Environment must be selected and loaded into the OO-Browser via {`C-c C-o'}. When the browser user interface is displayed, use {`q'} to quit. Alternatively, you can load an Environment without invoking the browser user interface by using {`M-x br-env-load RET'}. The standalone browser features will use the newly loaded Environment. The commands that are available for standalone use include: `br-add-class-file' Add a file of classes to the current Environment. *Note Adding and Deleting Classes::. `br-find' Interactively complete class or ELEMENT name and jump to its definition. `br-find-class' Display file of class text matching CLASS-NAME in VIEW-ONLY mode if non-nil. `br-complete-type' Perform in-buffer completion of a type or element identifier before point. `br-class-path' Return full path, if any, to CLASS-NAME. With optional prefix argument INSERT non-nil, insert path at point. All of these commands provide full completion. *Note Completing Names::, based upon the current OO-Browser Environment. When editing and debugging code, one often wants to look at a class or element definition without having to invoke the browser to locate it. The `(br-find)' command does exactly that by prompting for a name and then displaying for editing the class or element definition given by that name. The `(br-find-class)' command is similar. It prompts for a class name and then displays its source file in a viewable, read-only mode. To display a class file in an editable mode, send a prefix argument to this command. When writing code and entering class attribute definitions (variable definitions), one often has to repetitively enter class names as the static types for the attributes. The `(br-complete-type)' command completes and inserts a class name at point in the current buffer. The traditional key to bind such a command to is {`M-TAB'}. The following example illustrates its usage. my_list: LIN<-- (point is here) {`M-TAB'} is hit: my_list: LINKED_LIST The `(br-class-path)' command prompts for a class name and displays the full path of the associated class source file in the minibuffer. With a prefix argument, it inserts the path name at point in the current buffer. The following key bindings are recommended when using these standalone features: `(define-key eiffel-mode-map "\C-c\C-f" 'br-find)' `(define-key c++-mode-map "\C-c\C-f" 'br-find)' `(define-key lisp-mode-map "\C-c\C-f" 'br-find)' `(define-key objc-mode-map "\C-c\C-f" 'br-find)' `(define-key smalltalk-mode-map "\C-c\C-f" 'br-find)' ;; {`C-M-i'} means {`M-TAB'}. `(define-key eiffel-mode-map "\C-\M-i" 'br-complete-type)' `(define-key c++-mode-map "\C-\M-i" 'br-complete-type)' `(define-key lisp-mode-map "\C-\M-i" 'br-complete-type)' `(define-key objc-mode-map "\C-\M-i" 'br-complete-type)' `(define-key smalltalk-mode-map "\C-\M-i" 'br-complete-type)' `(define-key eiffel-mode-map "\C-c\C-w" 'br-class-path)' `(define-key c++-mode-map "\C-c\C-w" 'br-class-path)' `(define-key lisp-mode-map "\C-c\C-w" 'br-class-path)' `(define-key objc-mode-map "\C-c\C-w" 'br-class-path)' `(define-key smalltalk-mode-map "\C-c\C-w" 'br-class-path)'. *Note Eiffel Specifics::, for an Eiffel-specific standalone browser feature. File: oo-browser.info, Node: Languages, Next: Features, Prev: Standalone, Up: Top Language-Specific Notes *********************** * Menu: * C Specifics:: * C++ Specifics:: * CLOS Specifics:: * Eiffel Specifics:: * Java Specifics:: * Objective-C Specifics:: File: oo-browser.info, Node: C Specifics, Next: C++ Specifics, Prev: Languages, Up: Languages C Specifics =========== The BR-C-TAGS-FLAG variable controls whether or not C constructs are included within C and C-based language Environments. By default, this flag is true. Use `M-x br-toggle-c-tags RET' to toggle its value. If you set it false before building an Environment, then C constructs will not be included in the Environment. (Note that C functions are always included in C++ Environments, regardless of this flag value.) If you wish to build an Environment whose source code is entirely C, ensure that the BR-C-TAGS-FLAG is enabled and then select C++ when asked for the language to browse. In the future, a language setting for C will probably be added. C constructs are grouped into default classes for browsing. The elements of each default class are the instances of the associated construct within the Environment. Use normal element/feature commands to browse each instance. DEFAULT CLASS C CONSTRUCT -------------------------------------- [constant] #define constant [enumeration] enum {} [function] non-member function() [macro] #define macro() [structure] struct {} [type] typedef {} [union] union {} File: oo-browser.info, Node: C++ Specifics, Next: CLOS Specifics, Prev: C Specifics, Up: Languages C++ Specifics ============= *Note C Specifics::, for details on C-specific support within C++ Environments. * Menu: * C++ Element Selection:: Source Code Element Selection * C++ Settings:: File: oo-browser.info, Node: C++ Element Selection, Next: C++ Settings, Prev: C++ Specifics, Up: C++ Specifics Source Code Element Selection ----------------------------- C++ pure virtual function declarations, which specify method interfaces but no implementation, appear in class feature listings. The function name is preceded by the `"> "' string to identify the function as a pure virtual (deferred) function. Pure virtuals may be treated like any other member functions within the browser. Since there is no definition for such a function within the class in which it is listed, its declaration will be shown instead, when requested. Friend functions and friend classes give members of another class access to the private parts of the current class. They appear in class feature listings preceded by the `"% "' string. The keys, {`v'} or {`e'}, display the friend declaration within the current class. Use {`V'}, `(br-view-friend)' to view the definition of the friend class or function. Methods and operators associated with creating and destroying objects are preceded by the `"+ "' string in listing buffers. All other method listing entries are preceded by the `"- "' string. One can jump from a C++ declaration to its definition by clicking the Action Key when within the declaration. Most importantly, once a class header file is displayed, simply click on a method declaration to see its corresponding definition. Each feature declaration should be terminated with a semicolon to ensure accurate scanning. If the method is inherited from another class, a message at the bottom of the frame will describe which class the method is defined in once the browser displays the method definition. Parent classes may be browsed in a similar manner by clicking on their names in an inheritance or declaration clause. It is therefore important to click on the method name part of a declaration when that is the element desired. Include files may be browsed by selecting their inclusion declarations (#include ...) within a source file. Include files delimited by double quotes are searched for in the following places: first, the directory of the current source file, then the directories listed in the variable C++-INCLUDE-DIRS, and then in any directories included in the current environment. Include files delimited by angle brackets are searched for in the following places: first, the directories listed in the variable C++-INCLUDE-DIRS, then the directories listed in the variable C++-CPP-INCLUDE-DIRS, and then in any directories included in the current environment. The variable C++-CPP-INCLUDE-DIRS should hold a list of the standard directories searched by your C++ pre-processor. Each directory entry must end with a directory separator. On UNIX systems, this is the '/' character. File: oo-browser.info, Node: C++ Settings, Prev: C++ Element Selection, Up: C++ Specifics C++ Settings ------------ By default, `class', `struct' and `union' definitions all constitute class definitions to the C++ OO-Browser. If you prefer some other criteria, you will need to modify the definition of C++-CLASS-KEYWORD in `br-c++.el'. If you find that the browser is not scanning some of your C++ source files, you may be using file suffixes which it does not recognize. Examine the value of C++-SRC-FILE-REGEXP and add any special file suffixes you use to it. File: oo-browser.info, Node: CLOS Specifics, Next: Eiffel Specifics, Prev: C++ Specifics, Up: Languages CLOS Specifics ============== * Menu: * CLOS Method Handling:: Method Handling * CLOS Settings:: File: oo-browser.info, Node: CLOS Method Handling, Next: CLOS Settings, Prev: CLOS Specifics, Up: CLOS Specifics Method Handling --------------- In CLOS, methods may have typed parameters of the form, `(<parameter-name> <class>)'; these are called "specialized parameters". Each such parameter defines the method within `<class>'. Thus, a single method definition can generate methods associated with many classes. The OO-Browser lets you navigate to a method definition from any of the classes for which it is defined, since a method is included as an element of each of its constituent classes. CLOS permits compile-time computation of the `<class>' of a specialized parameter, through use of the expression, `(eql <form>)'. Since the OO-Browser cannot perform this computation, it treats such a parameter as non-specialized. Methods may also contain non-specialized parameters of the form, `<parameter-name>'. The type of each such parameter defaults to the default root class `t' in CLOS. But a method is only included in the class `t' by the OO-Browser if none of its parameters are specialized. Otherwise, methods with more specific types which happened to include one or more non-specialized parameters would appear to not have a more specific type than `t'. File: oo-browser.info, Node: CLOS Settings, Prev: CLOS Method Handling, Up: CLOS Specifics CLOS Settings ------------- The OO-Browser automatically works with CLOS class and method definitions. But Lisp contains many other standard object types such as functions, macros and variables which you may wish to browse. These are handled through a configuration variable as explained below. The CLOS-ELEMENT-TYPE-ALIST variable determines the Lisp definition constructs that the browser looks for and the associated default class under which instances of each construct type are grouped. Each element in the association list is a cons cell whose first part is the function name string that defines an instance of a particular type, e.g. `"defun"'. The second part is a default class name, a string, under which to assign each instance of the type, e.g. `"function"'. The OO-Browser always displays default class names with square brackets around them, e.g. `[function]', to distinguish them from classes defined within the Environment. Here is the default CLOS-ELEMENT-TYPE-ALIST setting: '(("defconstant" . "constant") ("defconst" . "constant") ("defun" . "function") ("defgeneric" . "generic") ("defmacro" . "macro") ("defpackage" . "package") ("defparameter" . "parameter") ("defsetf" . "setfunction") ("defstruct" . "structure") ("deftype" . "type") ("defvar" . "variable") ("fset" . "function")) The CLOS-DEF-FORM-WITH-ARGS-REGEXP is a regular expression which includes a subset of the definition symbol names from CLOS-ELEMENT-TYPE-ALIST, namely those which require an argument list to uniquely distinguish them from other elements, e.g. functions. File: oo-browser.info, Node: Eiffel Specifics, Next: Java Specifics, Prev: CLOS Specifics, Up: Languages Eiffel Specifics ================ Eiffel support has now been updated to Eiffel version 3, to the best of our knowledge. If you find any problems, please report them to <oo-browser@hub.ucsb.edu> (this is a public mailing list). * Menu: * Eiffel Listings:: * Eiffel Element Selection:: Source Code Element Selection * Eiffel Settings:: File: oo-browser.info, Node: Eiffel Listings, Next: Eiffel Element Selection, Prev: Eiffel Specifics, Up: Eiffel Specifics Eiffel Listings --------------- Eiffel entities are categorized when shown within OO-Browser listing buffers. Classes are shown by name, without any prefix. Features are shown by name but are preceded by a special character that indicates the kind of feature. The following table describes each prefix. `-' precedes regular routines; `=' precedes attributes; `1' precedes once routines, which create shared objects; `>' precedes deferred features, which are specified but not defined within this class; `/' precedes external features, which are defined in a non-Eiffel language. File: oo-browser.info, Node: Eiffel Element Selection, Next: Eiffel Settings, Prev: Eiffel Listings, Up: Eiffel Specifics Source Code Element Selection ----------------------------- One can jump from an Eiffel element reference to its definition by clicking the Action Key when within the reference. Selection of a feature name in an export clause displays the feature definition, even if it is renamed several times within ancestors. Parent classes may be browsed in a similar manner by clicking on their names in an inheritance or declaration clause. The following example of locating a renamed feature is taken from an actual set of Eiffel library classes: User selects feature `subwindow' of `POPUP_MENU' inherited from `WINDOW' which renames `child' as `subwindow' inherited from `TWO_WAY_TREE' which renames `active' as `child' inherited from `TWO_WAY_LIST' inherited from `LINKED_LIST' which defines `active'. The browser would display the feature `active' and explain to the user that feature `subwindow' of class `POPUP_MENU' is inherited from feature `active' of class `LINKED_LIST'. Location of this sort of feature definition would be incredibly tedious without programmatic support. The algorithm used to locate features is dynamic, so if another class were inserted into the inheritance structure given above, the feature definition would still be located properly. File: oo-browser.info, Node: Eiffel Settings, Prev: Eiffel Element Selection, Up: Eiffel Specifics Eiffel Settings --------------- Be sure that the 'inherit' and 'feature' clauses in your classes begin in column 0; otherwise the browser parser will not work properly. If you prefer some other indentation style, you will need to slightly alter `(eif-get-parents-from-source)' in `br-eif.el'; specifically, the lines that contain '^inherit' and '^feature'. Emacs has a feature called error parsing which lets one quickly jump to the line of code that supposedly triggered an error. (*Note Compilation Errors: (emacs)Compilation, for information on error parsing.) Some object-oriented language compilers display the name of the class and line number with each error message but do not include the filename containing the class source code. Emacs then has no way of parsing the error message. The browser class location facilities enable one to perform error parsing across any set of classes in a single Environment, given only this type of message. Interactive Software Engineering's Eiffel compiler is an example of a compiler that produces this type of error. The code for parsing these Eiffel error messages is included in `eif-ise-err.el'. File: oo-browser.info, Node: Java Specifics, Next: Objective-C Specifics, Prev: Eiffel Specifics, Up: Languages Java Specifics ============== Java abstract method declarations, which specify method interfaces but no implementation, appear in class feature listings. The method name is preceded by the `"> "' string to identify the method as an abstract (deferred) method. Abstract methods may be treated like any other methods within the browser. Since there is no definition for such a method within the class in which it is listed, its declaration will be shown instead, when requested. Native methods are like abstract methods in that only their interfaces are specified in Java. Unlike abstract methods, their method bodies are defined in external languages such as C to allow for machine-specific dependencies. Native methods are listed in the browser prefixed by the `"/ "' string, indicating that they are divided between Java and another language. Methods associated with creating and destroying objects are preceded by the `"+ "' string in listing buffers. All other method listing entries are preceded by the `"- "' string. Java interface specifications, which specify protocols to which classes must conform, are treated just like class definitions in browser listings. All the methods of such interfaces are abstract, however. File: oo-browser.info, Node: Objective-C Specifics, Prev: Java Specifics, Up: Languages Objective-C Specifics ===================== *Note C Specifics::, for details on C-specific support within Objective-C Environments. The OO-Browser supports browsing Objective-C classes, methods, categories and formal protocols. Earlier sections of this manual explain how to browse these entities. This section documents Objective-C language specifics, including variable settings. Objective-C entities are categorized when shown within OO-Browser listing buffers. Classes are shown by name, without any prefix. Methods are shown by name but are preceded by a special character that indicates the kind of method. The following table describes each prefix. `-' precedes instance methods; `+' precedes class (factory) methods that affect the factory object for the class. * Menu: * Objective-C Categories:: * Objective-C Protocols:: * Objective-C Element Selection:: Source Code Element Selection * Objective-C Settings:: File: oo-browser.info, Node: Objective-C Categories, Next: Objective-C Protocols, Prev: Objective-C Specifics, Up: Objective-C Specifics Objective-C Categories ---------------------- An "Objective-C category" is an internal class grouping that specifies and implements a set of related class features. The aggregation of all of the categories defined by a class and its ancestors represents the complete class definition. The OO-Browser can list and browse the source for: the categories of a class, all class categories in an Environment, and the classes which implement a category. *Note Browsing Categories::, for details. File: oo-browser.info, Node: Objective-C Protocols, Next: Objective-C Element Selection, Prev: Objective-C Categories, Up: Objective-C Specifics Objective-C Protocols --------------------- An "Objective-C protocol" is an interface specification to which a class may conform. The protocol includes a set of method signatures which any conforming class must implement. One protocol may inherit from a list of other protocols, and thus expand the set of methods which a conforming class must implement. The OO-Browser can list and browse the source for: the protocols to which a class conforms, all protocols in an Environment, and the implementors of a protocol. *Note Browsing Protocols::, for details. File: oo-browser.info, Node: Objective-C Element Selection, Next: Objective-C Settings, Prev: Objective-C Protocols, Up: Objective-C Specifics Source Code Element Selection ----------------------------- One can jump from an Objective-C declaration to its definition by clicking the Action Key when within the declaration. Most importantly, once a class header file is displayed, simply click on a method declaration to see its corresponding definition. If the method is inherited from another class, a message at the bottom of the frame will describe which class the method is defined in once the browser displays the method definition. Parent classes may be browsed in a similar manner by clicking on their names in an inheritance or declaration clause. It is therefore important to click on the method name part of a declaration when that is the element desired. Include files may be browsed by selecting their inclusion declarations (#import ...) within a source file. Include files delimited by double quotes are searched for in the following places: first, the directory of the current source file, then the directories listed in the variable OBJC-INCLUDE-DIRS, and then in any directories included in the current environment. Include files delimited by angle brackets are searched for in the following places: first, the directories listed in the variable OBJC-INCLUDE-DIRS, then the directories listed in the variable OBJC-CPP-INCLUDE-DIRS, and then in any directories included in the current environment. The variable OBJC-CPP-INCLUDE-DIRS should hold a list of the standard directories searched by your Objective-C pre-processor. Each directory entry must end with a directory separator. On UNIX systems, this is the '/' character. File: oo-browser.info, Node: Objective-C Settings, Prev: Objective-C Element Selection, Up: Objective-C Specifics Objective-C Settings -------------------- By default, the `@interface' keyword indicates a class definition to the Objective-C OO-Browser. If you prefer some other criteria, you will need to modify the definition of OBJC-CLASS-KEYWORD in `br-objc.el'. If you find that the browser is not scanning some of your Objective-C source files, you may be using file suffixes which it does not recognize. Examine the value of OBJC-SRC-FILE-REGEXP and add any special file suffixes you use to it. File: oo-browser.info, Node: Features, Next: Commands, Prev: Languages, Up: Top OO-Browser Features ******************* * Support for Eiffel, C++, Objective-C, Smalltalk, Java and Common Lisp and its Object System (CLOS) is included. Additionally, support for browsing large amounts of material in Info format by node name (a popular online documentation format with cross references and hierarchical structure) is include. All languages provide class browsing via either a textual or a graphical interface. * Method browsing is supported for C++, Objective-C, Eiffel and CLOS. CLOS supports browsing all elements defined with (def* constructs. In-source feature browsing is also supported for all of these languages. One simply selects a feature name to jump to its corresponding source. Method name overloading in C++ and inherited feature renaming in Eiffel are fully supported. * C code browsing is supported for C++, Objective-C and C source code. * Objective-C category and formal protocol browsing are supported. * C++ parameterized template classes and methods are supported. * Building Environments is fast compared to many other tools and browser startup once an Environment has been built is very fast. Response times on workstations are excellent; for example, in one test case, less than two real seconds were required to display a set of complex inheritance graphs involving over 400 classes. * Class inheritance networks may be displayed. Either a single inheritance level (parents or children) or the entire inheritance network (ancestors or descendants) for a set of classes may be shown. * Multiple inheritance support is built-in, where applicable. * The user need not know the location of class source; the browser will display or edit a class source based solely upon its class name. * Immediate switching among languages is allowed. One can switch from Eiffel browsing to C++ browsing in an instant, if so desired. Or simply run two browsers side by side. * Class files may be added, replaced or deleted one at a time or as a group by specifying a root directory below which all class files are found, including those in subdirectories. * The browser uses class source code only, hence no compiler is necessary for proper browser operation. * Library (stable) and System (in development) classes may be maintained and listed separately or together. Any number of Libraries and Systems may be combined for listing in a single Environment. There are no fixed limits on the number of classes per Environment nor on the number of Environments that may be browsed. * The number of listing windows is limited only by the frame width and the width setting used for listing windows. * Statistics on classes and Environments may be displayed. * Language-specific class information may be shown. Presently this feature is supported only for Eiffel. A listing of class parents, attributes, routines and best guess (highly accurate) list of routine calls may be displayed. Outputs from the Eiffel 'short' and 'flat' commands may also be shown. * Machine-independent mouse support is included along with an extremely intuitive point and click interface. The OO-Browser is pre-configured for use with the X window system, NEXTSTEP, Sunview or Apollo's DM window system under InfoDock, Emacs V19, XEmacs, Epoch, and Emacs V18. * Popup and pulldown command menus are available under InfoDock, Emacs V19 and XEmacs. * All browser outputs are text which may be edited as desired or saved to files. * A single key provides ASCII ordering of class names, ascending or descending, including those from inheritance trees. Classes may be easily located by matching a regular expression or string to the set of class names in an Environment, with repeated searches incrementally narrowing the selected set. * Browser functions may be used standalone within the editor without using the multi-windowed browser interface. One useful example is to point to a class name such as a parent class in the text of another class and have the parent's source appear in an editable fashion. An alternative editor and viewer may be selected to adapt the browser to personal taste. * The browser is adaptable to any class-based object-oriented language. It works best with languages that focus on static class creation such as Eiffel and C++. Those that use dynamic (runtime) class creation such as CLOS must be interfaced to the browser so that classes created at runtime are added to the browser's Environment. * The OO-Browser is integrated with the powerful GNU Emacs editor; it works on any UNIX system display supported by Emacs. Most browser commands may be executed by direct selection, providing a very natural interface. * All source code, over 400 kilobytes, is included and is heavily documented. File: oo-browser.info, Node: Commands, Next: Glossary, Prev: Features, Up: Top OO-Browser Command Descriptions ******************************* The following documentation is meant for programmers who want to modify the OO-Browser but is included here since some users of the OO-Browser may find it useful. All commands that are bound to keys and that are specific to the OO-Browser are listed here. Within each command description, identifiers shown in all capitals are the names of the command's formal arguments; all formal arguments are presented in the order in which they are required by the command. If a command takes optional arguments, the first optional argument is labeled *optional*; all following arguments are assumed to be optional. `br-add-class-file {`C-c ^'}' Adds a file of classes to the current Environment. Interactively or when optional CLASS-PATH is nil, defaults to current buffer file as CLASS-PATH. If optional LIB-TABLE-P is non-nil, add to Library Environment, otherwise add to System Environment. If optional SAVE-FILE is t, the Environment is then stored to the filename given by BR-ENV-FILE. If SAVE-FILE is non-nil and not t, its string value is used as the file to which to save the Environment. `br-ancestors {`a'}' Display ancestor tree whose root is the current class. With optional prefix ARG, display all ancestor trees whose roots are visible classes at the current level. ARG = -1 inverts current class ancestry tree. That is, it shows branches going down towards the root class, so that parents appear above children. ARG < -1 inverts all ancestry trees. `br-at {`@'}' Display current class location in the inheritance graph. The class is displayed among both its ancestors and descendants. With optional prefix ARG, display location for all visible classes at the current level. `br-buffer-menu {`b'}' Display selection list of buffers with attached files in viewer window. `br-children {`c'}' Display children of current class. With optional prefix ARG, display children of all visible classes at the current level. `br-class-stats {`M-c'}' Display statistics summary for current class. Optional prefix arg PROMPT means prompt for class name. `br-copyright' Display browser copyright information in viewer window. `br-count {`#'}' Count number of classes visible in current listing buffer. Print text result in minibuffer when called interactively. `br-delete {`C-c C-d'}' Delete class from current Environment. Optional prefix arg PROMPT means prompt for class name. `br-descendants {`d'}' Display descendant tree whose root is the current class. With optional prefix ARG, display all descendant trees whose roots are visible classes at the current level. `br-edit-entry {`e'}' Edits source for any browser listing entry, such as a class or a feature. Optional prefix arg PROMPT means prompt for entry name. `br-env-create {`C-c C-c'}' Create and save the specification of a new OO-Browser Environment. Interactively prompt for the Environment file name or use optional ENV-FILE. Interactively prompt for the Environment language to use or use optional LANG-PREFIX as language indicator. Return the name of the Envir spec file created. Do not build the Environment. Use 'br-env-build' to construct an Environment from its specification. `br-env-load {`C-c C-l'}' Load browser Environment or spec from optional ENV-FILE or 'br-env-file'. Non-nil PROMPT means prompt user before building tables. Non-nil NO-BUILD means skip build of Environment entirely. Return t if load is successful, else nil. `br-env-rebuild {`C-c C-e'}' Rescan System and Library sources associated with the current Environment. `br-env-save {`C-c C-s'}' Save changed Environment to file given by optional SAVE-FILE or 'br-env-file'. `br-env-stats {`M-e'}' Display summary for current Environment in viewer window. With optional prefix ARG, display class totals in minibuffer. `br-exit-level {`x'}' Return to prefix ARGth previous inheritance level listing. The command is ignored with ARG < 1. `br-find' Interactively completes class or feature ELEMENT-NAME and jumps to its definition. Returns ELEMENT-NAME or signals an error. `br-feature-signature {`F'}' Show full feature signature in the view window. With optional prefix ARG, display signatures of all features from the current buffer. `br-help {`h'}' Display browser operation help information in viewer window. `br-help-ms {`H'}' Display browser mouse usage help information in viewer window. `br-entry-info {`i'}' Display attributes of the current entry in the viewer window. `br-implementors {`I'}' Display hierarchy of classes that define current feature. Ignore inherited features. With optional prefix ARG, display implementors of all features at the current level. `br-kill {`C-c C-k'}' Kill buffer in viewer window and redisplay help text. `br-lib-top-classes {`l'}' Display list of top level Library classes. With prefix ARG, display all Library classes. `br-lib-rebuild {`L'}' Rescan Library components of the current Environment. `br-match {`m'}' Show all class names in current Environment that contain optional EXPR. Nil value of EXPR means prompt for a value. With optional prefix ARG, EXPR is treated as a string. By default, it is treated as a regular expresion. AGAIN non-nil shows the number of classes MATCHED from the last search, allowing repeated narrowing of the search set. Empty EXPR when AGAIN is nil matches to all classes in the Environment. `br-match-entries {`M'}' Show all entries in current listing that contain optional EXPR. Nil value of EXPR means prompt for a value. With optional prefix ARG, EXPR is treated as a string. By default, it is treated as a regular expresion. AGAIN non-nil means show the number of entries MATCHED from last search, allowing repeated narrowing of the search set. Empty EXPR when AGAIN is nil matches to all entries in the listing. `br-next-entry {`C-n'}' Move point vertically down prefix ARG number of lines in listing buffer. `br-order {`o'}' Order current browser listing window entries. With prefix ARG other than 1 (the default), don't remove leading space from entry lines before ordering. Negative ARG means order in descending Ascii sequence, otherwise order in ascending sequence. `br-parents {`p'}' Display parents of current class. With optional prefix ARG, display parents of all visible classes at the current level. `br-prev-entry {`C-p'}' Move point vertically up prefix ARG number of lines in listing buffer. `br-quit {`q'}' Quit browser. With optional prefix ARG, delete window configurations and listing buffers associated with the browser. `br-refresh {`C-c C-r'}' Restore OO-Browser to its state upon startup. `br-resize-narrow {`C-x -'}' Resize listing windows so are narrower by 10 characters. `br-resize-widen {`C-x +'}' Resize listing windows so are wider by 10 characters. `br-features {`f'}' Display features/elements of the current class (prefix ARG = 1) or of the current listing if ARG is other than 0 or 1. With ARG = 0, the value of the variable, BR-INHERITED-FEATURES-FLAG, is toggled and no other action is taken. If BR-INHERITED-FEATURES-FLAG is `t', all features of each class are shown. If `nil', only lexically included features are shown and if the features of a single class are requested and none are defined, the class definition is displayed so that its feature declarations may be browsed. `br-sys-rebuild {`S'}' Rescan System components of the current Environment. `br-sys-top-classes {`s'}' Display list of top level System classes. With prefix ARG, display all System classes. `br-to-from-viewer {`C-c C-v'}' Move point to viewer window or back to last recorded listing window. `br-toggle-keep-viewed' Toggle the value of the BR-KEEP-VIEWED-CLASSES flag. `br-top-classes {`t'}' Display list of top level classes. With prefix ARG, display all Environment classes. `br-unique {`u'}' Eliminate adjacent duplicate entry names from the current listing window. If two adjacent entries look the same one is eliminated, even if they refer to different class elements. `br-version {`C-c #'}' Display browser version number. `br-view-entry {`v'}' Displays source for any browser listing entry. Optional prefix arg PROMPT means prompt for entry name. `br-view-friend {`V'}' With point on a friend listing entry, view its source code definition. With optional OTHER-WIN non-nil, display in another window. With optional SIG-AT-POINT-FLAG non-nil, assume point is within a friend signature in a source buffer. `br-view-full-frame {`1'}' Use full frame to display contents of viewer window. `br-viewer-scroll-down {`DEL'}' Scroll viewer window downward ARG lines or a windowful if no ARG. `br-viewer-scroll-up {`SPC'}' Scroll viewer window upward ARG lines or a windowful if no ARG. `br-where {`w'}' Display in minibuffer and return full path of a browser listing entry. Optional prefix arg PROMPT means prompt for entry name." `br-write-buffer {`C-c C-w'}' Write narrowed portion of current browser buffer to a file. `br-tree {`M-d'}' Start the `xbr' application with descendency tree of current class. With optional prefix ARG, a descendency tree for each class in current buffer. `br-tree-graph {`M-g'}' Start the appropriate tree application with the tree from current listing buffer. `br-tree-kill {`M-k'}' Prompt user whether to kill all `xbr' sub-processes. `br-tree-features-toggle {`M-f'}' Toggle between showing features and hiding them when `br-tree' is invoked to display descendants graphically.